.TH LIBPFM 3  "March, 2008" "" "Linux Programmer's Manual"
.SH NAME
libpfm \- a helper library to program Hardware Performance Units (PMUs)
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.SH DESCRIPTION
The libpfm library is a helper library which is used by applications to
help program the Performance Monitoring Unit (PMU), i.e., the hardware
performance counters of modern processors. It provides a generic and portable
programming interface to help setup the PMU configuration registers given a
list of events to measure.

A diversity of PMU hardware is supported, a list can be found below
under \fBSUPPORTED HARDWARE\fR. The library is primarily designed to be used in
conjunction with the Perfmon2 Linux kernel interface. However, at its core,
it is totally independent of that interface and could as well be used on other
operating systems. It is important to realize that the library does not make the
actual kernel calls to program the PMU, it simply helps applications figure out
which PMU registers to use to measure certain events or access certain advanced
PMU features. 

The library logically divides PMU registers into two categories. The
performance monitoring data registers (PMD) are used to collect results, e.g.,
counts. The performance monitoring configuration registers (PMCS) are used
to indicate what events to measure or what feature to enable. Programming the
PMU consists in setting up the PMC registers and collecting the results in the
PMD registers. The central piece of the library is the \fBpfm_dispatch_events\fR
function.

The number of PMC and PMD registers varies between architectures and
CPU models. The association of PMC to PMD can also change. Moreover
the number and encodings of events can also widely change. Finally, the
structure of a PMC register can also change. All these factors make it
quite difficult to write monitoring tools.

This library is designed to simplify the programming of the PMC registers by
hiding the complexity behind a simple interface. The library does this without
limiting accessibility to model specific features by using a layered design.

The library is structured in two layers. The common layer provides an interface
that is shared across all PMU models. This layer is good enough to setup simple
monitoring sessions which count occurrences of events. Then, there is a
model-specific layer which gives access to the model-specific features.
For instance, on Itanium, applications can use the library to setup the
registers for the Branch Trace Buffer.  Model-specific interfaces have the
abbreviated PMU model name in their names. For instance,
\fBpfm_ita2_get_event_umask()\fR is an Itanium2 (ita2) specific function. 

When the library is initialized, it automatically probes the host CPU and
enables the right set of interfaces. 

The common interface is defined in the \fBpfmlib.h\fR header file.
Model-specific interfaces are defined in model-specific header files.
For instance, \fBpfmlib_amd64.h\fR provides the AMD64 interface.
.SH ENVIRONMENT VARIABLES
It is possible to enable certain debug output of the library using environment
variables. The following variables are defined:
.TP
.B LIBPFM_VERBOSE
Enable verbose output. Value must be 0 or 1. When not set, verbosity level
can be controlled with this function.
.TP
.B LIBPFM_DEBUG
Enable debug  output. Value must be 0 or 1. When not set, debug level
can be controlled with this function.
.TP
.B LIBPFM_DEBUG_STDOUT
Redirect verbose and debug output to the standard output file descriptor (stdout).
By default, the output is directed to the standard error file descriptor (stderr).
.sp
Alternatively, it is possible to control verbosity and debug output using
the \fBpfm_set_options\fR function.
.LP
.SH SUPPORTED HARDWARE
.nf
libpfm_amd64(3)     AMD64 processors K8 and Barcelona (families 0Fh and 10h)
libpfm_core(3)      Intel Core processor family
libpfm_atom(3)      Intel Atom processor family
libpfm_itanium(3)   Intel Itanium
libpfm_itanium2(3)  Intel Itanium 2
libpfm_montecito(3) Intel dual-core Itanium 2 9000 (Montecito)
libpfm_p6(3)        P6 processor family including the Pentium M processor
libpfm_powerpc(3)   IBM PowerPC and POWER processor families
                    (PPC970(FX,GX), PPC970MP POWER4, POWER4+, POWER5,
                    POWER5+, and POWER6)
.fi
.SH AUTHORS
.nf
Stephane Eranian <eranian@hpl.hp.com>
Robert Richter <robert.richter@amd.com>
.if
.PP
.SH SEE ALSO
libpfm(3), libpfm_amd64(3), libpfm_core(3), libpfm_itanium2(3),
libpfm_itanium(3), libpfm_montecito(3), libpfm_p6(3),
libpfm_powerpc(3).
.nf
pfm_dispatch_events(3), pfm_find_event(3), pfm_set_options(3),
pfm_get_cycle_event(3), pfm_get_event_name(3), pfm_get_impl_pmcs(3),
pfm_get_pmu_name(3), pfm_get_version(3), pfm_initialize(3),
pfm_regmask_set(3), pfm_set_options(3), pfm_strerror(3).
.fi
.sp
Examples shipped with the library
